PATHHardware Documentation > USB Devices > Mac OS USB DDK API Reference

Asynchronous Call Support

As a general rule, function calls to the USL complete asynchronously, with the exception of the functions listed here:

Since most USL functions complete asynchronously, it's important to allocate a parameter block in memory that will be available until the call completes, either with a call back or with an immediately returned error. Unless there is an immediate error, the parameter block cannot be reused until the completion routine is called. You can force the completion routine to be called for pipe transactions by calling the USBAbortPipeByReference function.

Asynchronous calls to the USL are supported by a completion routine mechanism. You pass a pointer to a completion routine in the USBPB parameter block. The completion routine is invoked when the USL function call completes, informing the driver of the calls completion.

The USB completion routine is of this form:

The fields required in the USBPB parameter block for all USL functions that return asynchronously are

--> pbLength

Length of parameter block

--> pbVersion

Parameter block version number

--> usbCompletion

The completion routine

--> usbRefcon

General-purpose value passed back to the completion routine

During the call to the completion routine, these fields are valid:

--> usbStatus

Status information

--> usbRefcon

General-purpose value passed back to the completion routine

-->

Any other call-specific fields marked as output from the call

-->

Any other call-specific fields used as input to and not output from the call

When the completion routine is called, the processing of the parameter block is complete and the parameter block is again available for use. The completion routine may use the same parameter block to make a new call to the USL. Polling the usbStatus field is not supported.

The execution level that the completion routine may be called back at is not guaranteed, unless otherwise specified in the individual routine specification. Completion usually occurs at secondary interrupt level, or at system task level. If the execution context is important to the operation of the code, the driver services call CurrentExecutionLevel can be used to discover the current execution level.

The driver services function CallSecondaryInterruptHandler2 can be used to continue execution at secondary interrupt level. The USBDelay * function can be used to effect a transition to task level. Note system task level is not the same as application task level, it may not be safe to make some Mac OS calls, particularly file system calls at system task level. Unless otherwise specified, all of the USL functions are safe to be called from either secondary interrupt level or from system task level.

*This functionality is missing in the USBDelay function in USB software versions 1.0 and 1.0.1, it does works as described with USB version 1.1 and higher. For USB versions earlier that 1.1, the Notification Manager can be used to effect a transition to task level.

Previous | Back Up One Level | Next |